

                    !meDDLe

            Version 2.20 1st May 2007

             Ray Favre  2006, 2007

             (Authored with Dr Wimp)


(This text Manual has been extracted from an Impression master. So
some formatting is lost and, of course, no pictures.....)


INTRODUCTION

!meDDLe is an application to convert OvationPro DDL document files into HTML documents. (Note: Not an OvationPro story saved as DDL.)

The DDL document format has the advantage (over Impression DDF) in that it captures a complete OvationPro document including any graphics - irrespective of how many chapters/stories are involved.

!meDDLes main aim is to provide a means for application manuals (like this one) to be converted into HTML for on-screen browsing, with a good chance of achieving formatting close to the original document plus a good measure of automatic links between sections/pages of the output HTML - and not forgetting the inclusion of pictures.

It will cope with multiple chapters (OvationPro-speak) and can output these as separate HTML pages - or, alternatively, pages can be triggered by a specific user-chosen Style.

Each HTML output page will automatically include a few additional helpful links to aid browser navigation, such as Next, Previous, Top, Return to Contents etc. - where appropriate.

An option to include a Contents page is given. This will show a list of links to each output HTML page - using the first line of text from each page as the list contents. Additionally, extra name markers can be inserted at user-chosen Style locations throughout the HTML output - and these will be included as links in the Contents list, indented within their appropriate main sections.

Graphics data can be automatically extracted and converted into html-friendly graphics files - and, for embedded graphics (again, OvationPro-speak), links will be automatically inserted into the HTML output so that the graphics will appear at the right places when viewed in a browser. (Non-embedded graphics will similarly be automatically extracted but no links will be inserted - see later.)

Finally, an option exists to insert external HTML links within the output text.

!meDDLe actively seeks to avoid reproducing headers/footers - which are unlikely to be needed in an HTML document.

!meDDLe does not reproduce coloured text.

!meDDLe makes no claims about handling all types of OvationPro document: it seeks solely to do a reasonable job on documents with straightforward structures i.e. text in flowing frames with embedded graphics. Even if it does not meet your complete needs its output will hopefully be sufficiently good to make any further tinkering much easier.

It is assumed that the user has at least a working knowledge of those basic HTML codes which alter text appearance.

Please remember that the actual appearance of the output can alter from browser to browser. For this reason best results are obtained using the simplest HTML mappings - see later. In particular, it seems reasonable to expect most browsers to be set up to show the h1 to h6 HTML codes in a sensible visual hierarchy.

If your OvationPro/DDL source document contains Artworks graphics you may need the !AWViewer to be installed. A copy is included in !meDDLes Res folder. It is normally best located in your !Boot.Resources folder, where it will be seen on computer start-up.

It is highly recommended that you follow the Example of use Section as your first practical foray - and it is then probably worth reading the Section Comments on usage before exposing !meDDLe to your own DDL input file.


PREPARING A DDL DOCUMENT FILE

A) From an Impression document:

1) Ensure that OvationPro has the !TransIMP mini-application located in the Applets sub-directory of the OvationPro application directory.

2) Run OvationPro.

3) Drag the Impression document file to the OvationPro iconbar icon and wait for the newly-converted OvationPro document to open. (This may take several seconds.)

4) Save the new document using the Save.DDL option (and save the document again as a normal OvationPro document, if required).

B) From an OvationPro document:

1) Run OvationPro.

2) Load the OvationPro document into it.

3) Save the document using the Save.DDL option.


Whichever route is taken, the resulting DDL document file is ready for use in !meDDLe.



INITIAL INSTALLATION AND START-UP


Copy the application to wherever you wish.

Double-clicking on the application icon will start it up in the usual way and place an icon on the iconbar.

Clicking on the iconbar icon (or dragging an Ovation DDL document file to it) will open the main window - as below.




The Red text at the bottom of this window prompts for the user actions that need to be taken to prior to processing (see next) - and also indicates progress during processing.


OVERVIEW


Before !meDDLe can process a DDL document file the following three steps (at least) are needed:

1) A DDL document file needs to be loaded.

2) A mapping needs to be made and confirmed.

3) A directory to hold the output file(s) needs to be set.


Step 1 must be taken first: but after that Steps 2 & 3 can be taken in any order. Any subsequent loading/re-loading of a DDL document file will require Step 2 to be taken again - but there is no need to carry out Step 3 again if the same directory is to be used.



THE BASIC STEPS


1) A DDL document file needs to be loaded.

This is done by dragging the DDL document file to the iconbar or to the main window.

The result can be seen in the next screen-shot: the Pale Yellow icon in the Input section at the top of the main window reflects the dragged file path, and most of the rest of the icons become enabled.

Note also that the Red text at the bottom of the window is now prompting for the next required user action.


When a DDL document file is loaded the application also automatically scans the file and extracts a list of all Styles actually used in the document (which may not include all the Styles which were available to be used in the source OvationPro document). This list is used in the next step.





2) A mapping needs to be made and confirmed.

Clicking on Show mapping... opens the Mapping window (see next screen-shot) which is simply a 2-column presentation showing the Styles extracted from the loaded DDL file on the left, and the HTML codes that are to be substituted for them on the right. At first, the right-hand column will be empty.

Using the menu buttons on the extreme right (or by loading a previously stored mapping file) the user can choose which HTML codes to substitute for (to map) any of the Styles. It is not necessary to map all (or any) Styles: those that are not mapped will be ignored in the subsequent processing.


When new mappings are chosen/loaded - or edited in any way - the changed HTML codes are shown in Red. When the user is happy with the list of mappings it is necessary to click on Confirm mapping before proceeding. All the HTML codes will then change to Black - and the Start processing button in the main window will be enabled (and the Red prompt text will change).

If a set of mappings has been confirmed and subsequent changes to the mapping list are made, then the Start processing button will be disabled again (and the Red prompt text will change correspondingly) - awaiting a new confirmation of the changed mapping.


Note also that clicking on the Confirm mapping button with <adjust> will make the confirmation and close the Mapping window.



3) A directory to hold the output file(s) needs to be set.

The ouput HTML files and any pictures will be placed in a directory of the users choice. So this step simply records that choice.

Create the output directory with whatever name and location you wish (or use any existing directory, of course) and then drag it to the main window. The corresponding Pale Yellow icon (in the Output section of the main window) reflects the directory path.

Again, the Red prompt test changes to show the next step. (If you have followed the above three steps in the shown order then the Red text will show Ready to process .... However if you have skipped any of these essential steps the Red prompt will remind you.)


When the above three steps have been completed the Start processing button will be enabled and the Red prompt will show Ready to process ....

If you wish to proceed using the default settings of the other items in the window it is just a matter of clicking the Start processing button.

The meaning of all the other items is contained in later sections but, for now, the default settings will produce:


- one HTML page for each chapter (OvationPro-speak) of the source OvationPro document - plus a summary HTML page called Contents. The latter is a list of links to the other HTML pages and the text of each item in this list is the first line of text on each page. None of the HTML pages will have a user-chosen title in its title bar.

- any pictures will be processed (with no compression if they are drawfiles, sprites or Artworks) and embedded pictures will be duly referenced in the HTML output.


PROCESSING PROGRESS

The processing progress is indicated bytwo methods: the Red text shows the stage that the processing is currently dealing with, and an hourglass shows the percentage of that stage that has been completed.

There can be up to three stages, depending on the users choices in the main window:

- scanning for pictures;

- extracting and processing pictures;

- processing the text (and producing the HTML output).

For example, with the default settings, all three stages are involved and the percentage figure will correspondingly climb from 0-100% three times - and the Red text will show when each stage starts.

However, the amount of time spent on each pass depends entirely on the specific input document and its graphic content and one or other of the passes may be too fast to be seen. Conversely, large graphics may cause the percentage progress to pause for a several seconds.


PICTURES/GRAPHICS

OvationPro can only display certain types of graphics files (currently Sprites, Drawfiles, JPEG files, Artworks files and EPS files - remembering that Drawfiles also capture several other types e.g. Tablemate files.). However, HTML browsers can only currently display JPEG. GIF and PNG files.

Consequently, in addition to extracting the graphics data from the DDL document file, !meDDLe also needs to convert most of the picture types to one or other of the html-friendly graphic file formats. In carrying out this process, all extracted pictures are saved as individual files - with incrementing numerical leafnames - to a separate folder (called Pics) in the user-chosen output directory.

JPEG and EPS files are simply extracted and saved to Pics unaltered. All other formats are converted to PNG format before saving to Pics. (EPS is therefore the only type of input graphics type which !meDDLe cannot properly handle at the moment - in that output files of EPS type cannot be displayed in a browser.)

In addition to extracting/converting graphics, !meDDLe will automatically generate appropriate links in the right place(s) for embedded graphics i.e. pictures which keep their relative place in the text. In these cases, each graphic position in the text is given a unique HTML image tag  of the form Pics/pic001.png, Pics/pic002.png, Pics/pic003.jpg etc. to link with the corresponding picture file in Pics.

For non-embedded graphics, !meDDLe will correctly extract (and convert, if necessary) the picture(s) and save it/them to the Pics folder, but it will not generate corresponding links in the HTML output - see later.

If the source OvationPro/DDL document includes any non-embedded graphics which have been copied from another graphic used in the same document then no duplication of the extracted/converted output graphic file is carried out. This may well lead to gaps in the numerical leafname references in the Pics folder, which is quite normal. (Note that this does not apply to copied embedded graphics which the DDL format treats as separate pictures.)



PROCESSING OPTIONS IN THE MAIN WINDOW


Output html pages

Instead of the default 1 page per chapter output, the user can choose either:

a) Single page - meaning that the whole DDL document file will be processed to give a single HTML page as output, irrespective of the number of chapters.

b) New page at Key Style - meaning that the user can designate a Style from the source document that will be used to trigger separate pages for the HTML output. Typically, the Style used for major section headings would be chosen here and the output pages will follow accordingly - irrespective of any chapter divisions.

The only restriction is that the chosen Key Style must have an HTML code mapped to it.



Title

This writable icon can be edited by the user to provide a title which will appear in the title-bar of each output HTML page - in the form Title - xxxx01, Title - xxxx02, etc. (where xxxx is the user-chosen output file leafname - see next item).

If the output option to produce a Contents page is chosen (see earlier) this title will also be used as its heading.


Output leafname

The user can choose a leafname for the HTML output pages by editing the writable icon in the usual way. The default is html - which will also be used if the writable icon is left blank.

As indicated above, this leafname will also appear in the title bar of each HTML 

page.


HTML links at Style

This option allows the user to specify a Style which will be used to create external HTML links in the output HTML document(s).

Typically, the original OvationPro document would include a Style intended to be applied exclusively to URLs within its normal text. For example, assume this Style is called Link and the OvationPro document includes the text .... on my website at http://www.rayfavre.me.uk .... The intention is that the URL (and only the URL i.e. the part in italics in the above example text extract) would have the Style Link applied to it. Then, by choosing Link from the Style menu available to the right of the HTML links at Style icon, the URL will automatically appear as an HTML link in the output document.

If the designated link Style is applied to an email address instead of a URL then the HTML link will automatically be prefixed with mailto: and work in the usual way.

The designated link Style does not need to be mapped, but if it is the mapping will be ignored.

Note that the created output HTML link will comprise exactly the text spanned by the designated Style, so it is essential to apply the designated Style carefully in the original OvationPro document - and it is important not to use this Style for other purposes.

Finally please note that in order for URL links to work correctly from the output HTML pages it is important for full URLs to be used i.e. do not forget the http:// part (or equivalent).

(The HTML link facility does not affect any mapping that may be applied as a result of other surrounding Styles being in force - as long as the designated link Style is wholly nested within them.)


HTML markers at Style

This option allows the user to specify a Style which will be used to trigger the placing of HTML name markers in the output document(s). The intention is that such markers will be used to navigate to specific parts within individual output HTML pages. Accordingly, if a Contents page is also chosen, it will also include links to each of these markers, arranged as indented links within each page link. (This facility does not affect any mapping that may be applied to the chosen Style: the mapping will still take place.)


Tabs?

If the author of the source OvationPro document has used the <Tab> key at any time in its preparation, its DDL document will contain a specific DDL code at the appropriate places. This option - which is off by default - determines whether !meDDLe automatically inserts a fixed number of spaces at those same places in the output HTML document. (This point is discussed further later.)


Contents page?

The state of this option button determines whether a Contents page is generated. As seen, it is ticked by default.

If chosen, the Contents page will contain a list of live links to each output page. The text for each link will normally be the text of the first paragraph of each page - which normally would be (and !meDDLe hopes it to be!) simply the heading line of the new page.

However, if the source document does not contain a heading line at the start of each page, the first paragraph could be a null string or excessively long - and in these cases !meDDLe takes special steps to present a neater output and to warn the user that something needs correcting (see Comments on usage).


Background colour

Clicking over this small square icon will display a simple menu of colours which can be used to select the background colour of both the output HTML page and any unused background of a converted graphic file. The default is White, and this - or a light Grey - is normally the best choice.


Picture options

There are three choices concerning pictures:


Process pics & insert refs

This is the normal situation - and is the default setting. With this choice, all picturs in the DDL document are extracted and converted to an html-friendly format - as described earlier. Further, any picture which is embedded (Ovation-speak) will be referenced in the correct place in the output HTML so that the picture will display when the page is viewed in a browser.


Insert refs, but dont process

This choice will include the correct picture references in the output HTML pages but will not extract/process the pictures themselves.

This choice is provided because picture extraction & processing is the time-consuming part of !meDDLes work and there are often occasions - after processing the pictures - when the user may wish to modify the text without altering the pictures.

This choice then allows the picture references to be updated and the text to be re-processed whilst keeping the originally-processed pictures untouched in the Pics folder. This can be a significant time saver when finalising an output HTML document.


Ignore pics

This choice simply ignores the prescence of pictures altogether; merely processing the text into an HTML output without any picture references.



Sprite compression

If a picture is in sprite format !meDDLe offers three choices for compressing the output PNG conversion. Similarly, pictures in drawfile or Artworks format are always converted first to sprite format and then into PNG for the final output.

For these cases, the three compression choices are High, Medium and None - which are largely self-explanatory.

None is chosen as default because it gives the quickest processing time. Also, users may be using pictures which are not particularly large and therefore do not need compression to help browsers to load quickly an HTML page in which they appear.

However, some sprite/drawfile/Artworks pictures can be very large and compression then becomes highly desirable. You will probably find that the Medium choice gives a high degree of compression without significantly lengthening meDDLes processing time. The High choice will produce the best compression but it will usually take significantly longer to do so.

It is not possible to give hard and fast guidance on which choice is best: it will depend entirely on your particular pictures.

Please remember that JPEG files will be extracted output without any further conversion, so it makes sense for the user to make these html-friendly before including them in the source OvationPro document.





OTHER USER ACTIONS

Editing the Mapping window

The earlier screen-shot of the Mappings window showed a straightforward case with some Styles left un-mapped and only one HTML code per Style.

It is allowable to set more than one HTML code against any Style. To do this, hold down <shift> whilst selecting the additional HTML code(s): the codes will then appear in the mapping entry (in Red, of course) as a comma-separated list. A typical use for this might be to make a heading both large and centred. (Using more than one HTML code for a Style needs to be used with care: it can, for instance, cause problems when setting HTML markers - see below.)

If you wish to clear an individual mapping entry you can select the (Clear) item in the HTML codes menu or, more simply, by pressing <adjust> over the entry itself. There is a Clear all button for clearing all mapping entries.

Note that any editing of the mapping list or new mapping file loading will disable the Start processing button, which will only be enabled/re-enabled when the Confirm mapping button is pressed. The Red prompt text will also change correspondingly.

(Note that, for user-convenience, the Ignores window is also accessible from the Mapping window - via the button at the top right of the window.)


Saving mappings

!meDDLe allows any set of confirmed mappings to be saved and easily retrieved for subsequent re-loading. Pressing the Save mapping... button in the Mappings window brings up a normal save window containing a suggested complete path which will save the mappings as a text-file directly to the Res directory within the application folder - from whence they can be retrieved at any time using the menu icon to the right of the Pale Yellow icon at the top of the Mappings window. (Alternatively, of course, the mappings can be saved anywhere else by normal save window dragging action, but the resulting file will then not be available on the above-mentioned menu, but rather will need to be dragged in.)



Headers/Footers and Ignore lists

Many source Impression/OvationPro documents contain Headers and/or Footers e.g. to show page numbering. A corresponding HTML document would probably not wish to have these and !meDDLe takes specific steps to allow them to be ignored.


Firstly, if a Header/Footer contains only insert codes e.g. {pageno} rather than text (with or without insert codes), then nothing needs to be done: the Header/Footer will be ignored in these cases.


However, if the Header/Footer contains text e.g. Page {pageno} then there would be unwanted occurrences of such text in the output HTML document. !meDDLe overcomes this problem by allowing the user to specify a list of text-to-be-ignored. Access to the list is by using the Show ignores button in the main window. This opens the following window:


This window has 12 writable icons (not all shown in the above screen-shot) - each of which can be used to enter text that is to be ignored if encountered on its own in a text frame.

Compiling a suitable ignore list for a particular DDL file derived from a source document with Headers and/or Footers may take a little trial and error (a good case for using thr Ignore pics choice) but it is not a difficult task. One thing to watch is that leading and/or trailing spaces in text may well be important to capture in the ignore list. For example, a Footer of the form:


Page {chapterno}.{pageno} - i.e. to show as Page 3.6


would need to have both the strings Page  (note trailing space) and . included as separate ignore strings.

As with mappings, sets of ignore strings can be saved as text files to the Res directory and retrieved from there via the menu icon at the top of the Ignore window.

Graphics in repeated headers/footers are a problem because currently !meDDLe cannot ignore them. This means that numerous unused and probably unwanted graphics files might be generated. It is strongly recommended that graphics in repeating headers/footers are eliminated in the source OvationPro document before saving as a DDL document file.

(Note that, for user-convenience, the mapping window is also accessible from the Ignores window - via the button at the top right of the window.)


HTML codes

The list of HTML codes which are available on the mapping menu is contained in the Messages formatted text-file Res.Messages.htmlcodes. As can be seen, this is restricted to those which modify the text in simple ways in a browser.

Provided you preserve the format, you can add to this list to explore the effects of other HTML codes - but you are on your own...


User-changeable system variables

!meDDLe uses four system variables to set certain limits. They are:

meDDLe$MaxPages - (initially set to 50) maximum number of HTML output pages allowed.

meDDLe$MaxStyles - (initially set to 50) maximum number of Styles allowed in input DDL document file.

meDDLe$MaxPics - (initially set to 100) maximum number of pictures allowed in input DDL document file.

meDDLe$MaxMarkers - (initially set to 100) maximum number of name markers (see earlier) allowed in output HTML documents.

meDDLe$MaxContentsLength - (initially set to 80) maximum length of text for links in Contents page. (Any curtailed text is reported at end of processing.)


These system variables are, as usual, set in the applications !Run file and their values can be changed by the user if required. (Specific error messages will indicate when any one of these system variables needs increasing. Note that increasing any value might mean that the WimpSlot value - in the same !Run file - will also need to be increased.)




COMMENTS ON USAGE


!meDDLe works best when the OvationPro source document for the DDL input file uses Styles exclusively (rather than Styles and Effects) and where those Styles are fairly straightforward and, where appropriate, properly nested.


!meDDLe is reasonably error-trapped to avoid crashing when it meets something unexpected or badly structured, but it might then produce unexpected or incomplete results.


If you experience problems it is often worthwhile to examine the OPro source of your DDL file. In particular, check carefully the application of any Styles designated for the key actions Html links, Html markers and New page. For example, have any of these Styles been applied to text that has subsequently been deleted but the Style now applies to a null string? Does the Style intended to be applied just to the title text of a new page actually hang over the previous page as well?


If your source document has been prepared over some time or has seen much editing it is probably worthwhile to clear all Styles and Effects from it and carefully re-apply just the ones you want. The reason for this is that  it is quite usual for a much-edited source document to have Styles badly nested and also applied in no longer relevant places. As !meDDLe will faithfully seek to apply your mapping choices to every instance of the Styles it finds, an untidy source document can lead directly to unexpected output results.


The order in which Styles are applied in the original OvationPro document can be important to !meDDLes output - particularly in cases where the HTML mapping seeks to replicate indented paragraphs with the use of the HTML code blockquote and the indented paragraph also contains other mapped Styles e.g. a Bold Style within an indented paragraph. In these cases it is important to apply the paragraph indenting Style before any other Styles are applied to the indented text. Otherwise there is a high risk that the HTML output will not appear as intended.


It is also worthwhile to think first about how you want the HTML conversion to appear to the user. It is probably unlikely that you will actually want a direct copy of the Impression/Ovation version - headers/footers are a prime example (remove them if you can, particularly if they contain graphics).


Further, you will want your individual HTML pages to load reasonably quickly, so it is important to ensure that no page involves a large download - which means that you might want the output to be split into a larger number smaller pages if you are using graphics.


Please note that the first output page (apart from the Contents, where appropriate) will always start at the start of the source document, irrespective of which output option is chosen. This means that if you wish to use the New page at Key Style option and the source document has an overall title before the paragraph formatting starts (like this Manual) you may get the first page break immediately after the title. There is a simple way around this - see Example of use later.


The usefulness of the Tabs? option will vary from document to document and it is simply a matter of suck it and see. It probably works best when the <tab> key was used only at the beginning of a line in the original document.


Apart from a very few reserved characters (and a few entities) - see How it works later - !meDDLe does not (yet?) attempt to convert all HTML entities into their special codes. The main reason for this is that the browsers I have tried do not seem to have any trouble with handling the entities and so laziness got the vote. It would probably not be difficult to incorporate these conversions but it might slow things down.


Choosing to include a Contents page is usually well worthwhile. Special steps have been taken to avoid blank links on this page and you may sometimes find a link with the text (Dummy link to Section X). This avoids a blank link which would otherwise have occurred and this event is almost certainly the result of an empty New page Style existing somewhere - which should be corrected.


Rightly or wrongly, !meDDLe expects that the very first paragraph (i.e. up to the first <return>) on any new page - including at the start of the document - is a typical heading - rather than a straightforward text paragraph extending over many lines. And it will be a list of each page heading which will appear on the Contents page.

For this reason, !meDDLe will deliberately curtail this text if it exceeds the length set in the !Run file by the system variable meDDLe$MaxContentsLength (see User-changeable system variables above). If this happens, the omitted text will be reported to you in a window at the end of the processing - for your action, as desired.


Even though they are automatically extracted and converted into files which end up in Pics, it is a pity that non-embedded pictures cannot be fully handled at the moment. The problem is that I have not yet found a suitable way to choose a location for such pictures in the HTML output - because, by definition, they are not located by reference to text position in the original document. However, it is a very simple process indeed for the user subsequently to decide the best location himself/herself and to add the necessary link in the right place in the right HTML page. Copying and editing one of the embedded-graphics links would make it even easier.


Finally, as indicated elsewhere, !meDDLe is by no means perfect. It is, for instance, possible to get some incorrect results when many different Styles exist around the place where a new HTML page is started. In essence, the simpler and cleaner the source document, the better !meDDLe will like it.


Id welcome your comments on any problems you find and also on how things might be improved.



EXAMPLE OF USE

The Example folder in the application directory has a DDL document (called DDLMan) prepared from an OvationPro version of this Manual.

Firstly, note that the document has seven chapters (Impression/Ovation-speak) four embedded pictures, and has a Footer showing the page number.


Test A

Open the Example folder to find DDLMan plus an empty folder called OutputDir.

The DDL document file was obtained by converting this Impression Publisher version to OvationPro and thence saved as a DDL document file, as described in the Introduction. No other changes have been made.

Run !meDDLe and - as Step 1) - drag DDLMan to the iconbar icon. This opens the main window.

Drag OutputDir to the window to complete Step 3).

Click on the Show mapping... button to bring up the Mapping window. Then click on the top right menu button in this new window and select mapping1 to load a pre-saved set of mappings - which will be in Red. Click Confirm mapping and the list changes to Black to show that the mappings are confirmed by the user. Note that the Start processing button is now enabled. This completes Step 2) and the Mapping window can now be closed if required.

The source document has a Footer in the form Page {pageno }, so click on Show ignores... to bring up the Ignore window - and then click on the menu icon at its top right and select ignore1, a pre-saved ignore file with just one item in it, namely Page  (note trailing space).

Leave all other settings in their default state.

Now click on Start processing. The red prompt text will change to show the stage being processed and an hourglass will appear with its percentage value showing the progress of the processing of the stage.

Wait for the hourglass to disappear and the Red text to show Finished. (OK to re-process). The Start processing button stays enabled.

Open up the OutputDir folder which should now contain eight HTML documents - one for each chapter of this document plus a Contents file. Double click on any of them to confirm that they give a reasonable representation of this Manual and confirm that the links in Contents lead directly to the other files. (But note that the HTML URLs in the Contacts section do not appear as live links.) Check the contents of Pics also: it should have four PNG files called pic001/png to pic004/png.


Note also that each HTML page has links to the next/previous pages (as appropriate), to return the user to the top of the page and back to the Contents page.


Test B

Delete all the above HTML pages (but not the Pics folder) and return to the main window. Choose the New page at Key Style option, and then use the associated right-hand menu button to show a list of the Styles used in the loaded DDL document file. Select Heading1.

Now move to the Html markers at Style icons and use the menu icon to select Heading2.

Then move to the Html links at Style icons and use the menu icon to select Link.

Finally, select the Insert refs, but dont process pics choice.

Now click on Start processing again - and OutputDir will eventually contain eleven HTML files. Double-click on them to confirm that this time the Manual has been split into pages based on Heading1 rather than chapters - although this will result in the same first page.

Also confirm that the Contents page now has indented sub-links within the first, third and fifth main section links - and that clicking on these loads the correct page as well as scrolling it to the appropriate place marked by Heading2.

Further, note that the URLs and email addresses in the Contacts section are now live links.

The Pics folder should be the same as before.


Test C

Delete all the output HTML files (but not the Pics folder) and repeat the exercise with the Single page option chosen, just to confirm the different result.


Test D

Check the sizes of the the picture files in Pics - then delete the pictures.

Repeat Test A but with the Medium sprite compression choice selected.

Confirm that the new output picture files in Pics are now much smaller and load more quickly when their HTML pages are viewed in a browser.


With these examples as a basis it is easy to explore all options and different mappings etc. in detail to gain familiarity.


Note in particular the use of the Style DummyHead1, which is identical to Heading1 and similarly mapped. It is used solely on the word Introduction at the first section heading after the title (instead of the Heading1 Style used for all other main section headings). This is to ensure that - in Test B above - a new page is not generated immediately after the title.





HOW IT WORKS


By brute force and a lot of ignorance!


A DDL file is a text-file with a mixture of actual text from the source document plus a multitude of coded items each surrounded by curly brackets. The header section of the file - often quite long - contains much coded information carrying the page/frame definitions etc. and most of this is of no interest to an HTML conversion process.

The key aspect from !meDDLes viewpoint is that these two types of items - text and codes - are never on the same line in the DDL file. Thus, when some text in the source document has a Style applied to it, the corresponding appearance in the DDL file is, typically, as follows:

{code to start Style}

text to which Style is applied

{code to end Style}

i.e all on separate lines in the DDL file.

There is often more than one curly-bracketed code on a line - and often multiple lines of continuous text - but text and codes never mix on any one line.

It is therefore possible to scan a DDL file on a line-by-line basis as the first step to interpreting its contents.


When a DDL file is loaded !meDDLe first opens it and scans through it line-by line until it reaches the Style definitions in the header. It then extracts into arrays each Style name plus the DDL files corresponding Style Code. It also makes a note of the file pointer position at the end of these Style definitions - to save some time by not bothering to scan these early lines again when the real processing starts.


Assuming the default settings are used, when the real processing starts - i.e. after a mapping has been confirmed and the output directory is known - !meDDLe scans the DDL document file three times (more or less).

The first scan looks for picture data, which is referenced and its file location noted. The second scan steps to each of the pictures in turn and extracts and converts them as necessary - with each picture being saved into Pics as a separate file. The third scan generates the HTML pages.

For each HTML page in turn, an output HTML file is opened and given a standard HTML heading - incorporating the user-chosen title and background colour instructions. The DDL document file is then examined line-by-line to test whether the line is a text-line or a code-line (and also if the code-line is the start of picture data).


If it is a text-line:

The line is sent to the output file - unless the text is exactly matched by an ignore entry. There are also checks to ensure a few HTML reserved characters (e.g. <) and entities are handled correctly - and in the special cases of the first line of a page and user-chosen markers, the text is also stored in arrays for the subsequent construction of the Contents output file.


The current list of reserved/entity characters handled specially by !meDDLe is:

        <

        >

        &

        Double-quotes (ASCII 34)

        Sexed single-quotes (ASCII 144/145)

        Sexed double-quotes (ASCI 148/149)

        Ligatures  and  (ASCII 158/159)

        Ellipsis  (ASCII 140)


If it is a code-line:

!meDDLe tests first for only a few types of DDL code: namely, {tab}, {newpara},         

{newpage}, {add/remove a Style} and {embedded picture location}. If any of these are present in the line all codes in that line are checked and appropriate action taken to output corresponding HTML codes to the output file - and sometimes to set flags for subsequent action.

In particular, any DDL Style code will cause the corresponding mapped HTML code to be added to the output file in the right place - except in the case of the Style selected for HTML links (if any) which will be used to insert a live HTML link and any mapping selected for it will be ignored.

In the special case where the code-line is the start of picture data (already extracted in the first scan) the first part of that data is used simply to advance the file pointer to step over this data i.e. to ignore it in this second scan. (Note that the location of embedded pictures is detected and acted upon, to give the correct HTML image tag reference at the right place(s) in the output file(s) so as to match the graphics files in the Pics folder in the output directory, as described earlier in this Manual.)



Depending on the output type selected, the correct end of an HTML output page is detected and after adding a standard HTML ending the current output file (an HTML page) is closed. This continues for as many HTML pages as necessaryuntil the end of the DDL document file is reached.


The last HTML page is then re-visited to ensure that some of its standard links are appropriate e.g. to delete the link to the Next page.


Finally, an HTML Contents file is constructed if the user has chosen this option.





HISTORY, CONTACTS & CREDITS


History

---------------------------------------

Version 2.20 1st May 2007


- Added option for user to control the amount of compression applied to sprite, drawfile and Artworks pictures.

- Added option to include picture references without processing the pictures.

- Added better progress reporting and user prompting.

- Improved handling of large picture files.

- Modified main window layout.

- Minor bug fixes.

- Upgraded to use Dr Wimp Version 4.70


---------------------------------------

Version 2.10 1st December 2006


- Added option to include external HTML links at a user-designated Style.

- Added ligatures  and  and ellipsis to entities handled separately.

- Improved user-access to Mapping and Ignores windows.

- Added title to output HTML Contents page.

- Minor bug fixes.

---------------------------------------

Version 2.03 1st June 2006


- Changed html marker referencing to match maximum allowable number of markers (as set in !Run file).

- Changed picture referencing to match maximum allowable number of pictures (as set in !Run file).

- Improved error reporting.

---------------------------------------

Version 1.00 18th December 2005

- First release

---------------------------------------

---------------------------------------


Contacts

Web-site:       http://www.rayfavre.me.uk

        http://www.rayfavre.me.uk/dwapps.html

        (directly to applications for downloading)

        http://www.rayfavre.me.uk/drwimp.html

        (directly to Dr Wimp package)


Email:  ray@rayfavre.me.uk



Credits

Rummaging around Harriet Bazleys !DDF2Html application gave me a lot of useful initial pointers.

In producing Version 2.00 David Pilling kindly supplied code for extracting the DDL graphics data and Pete Miller converted it to Basic for me.

The freeware utilities !ArtToSpr (by Tony Houghton), !Spr2Png (by Darren Salt) and !InterGif (by Peter Hartley) were all explored to meet the need to convert graphics files to an html-friendly format. In the end, this Version uses only the draw2spr and spr2png elements from !Spr2Png, but all three applications greatly added to my knowledge and both Tony Houghton and Darren Salt helped with more specific queries, for which I am grateful.

Martin Wuerthner was also helpful in revealing the practical meaning of some of the draw2spr and spr2png processing options - which are now put to good use in the sprite compression user-options.

The freeware Artworks viewer !AWViewer from Computer Concepts/Martin Wuerthner is also needed if Artworks graphics are involved. It is included with the application just in case - see Introduction.


!Spr2Png:               http://www.youmustbejoking.demon.co.uk/

!ArtToSpr:      http://www.realh.co.uk

!InterGif:              http://utter.chaos.org.uk/~pdh/software/intergif.htm

!AWViewer:      http://www.mw-software.com/


Contributors to the c.s.a.programming newsgroup also answered several of my queries very promptly and helpfully.

